home *** CD-ROM | disk | FTP | other *** search
/ BBS Toolkit / BBS Toolkit.iso / pc_board / tblt09b.zip / TOPBLT.DOC < prev    next >
Text File  |  1992-03-27  |  16KB  |  358 lines
  1. /////////////////////////////////////////////////////////////////////////////
  2. /////////////////////////////////////////////////////////////////////////////
  3.                                 TOPBLT v0.9b
  4.  
  5.                      PCBoard Top Users Bulletin Generator
  6.  
  7.                      For use with PCBoard Versions 14.5x
  8.  
  9.                       Copyright 1992 by Kendall Anderson
  10.                              ALL RIGHTS RESERVED
  11. /////////////////////////////////////////////////////////////////////////////
  12.                         This program is supported by:
  13.  
  14.                                Kendall Anderson
  15.                             486 Aspen Forest Drive
  16.                                Oakville, Ontario
  17.                                    L6J 6H7
  18.                                    CANADA
  19.  
  20. /////////////////////////////////////////////////////////////////////////////
  21. Documentation of TOPBLT version 0.9b, dated Mar. 27, 1992  (c) K. Anderson
  22. /////////////////////////////////////////////////////////////////////////////
  23.  
  24. ///////////////////// NOTE: THIS IS A BETA TEST VERSION /////////////////////
  25.  
  26.   Lazy Sysop's rule:
  27.  
  28.       "Long manuals are never printed and read completely"
  29.  
  30.  
  31.  
  32.         First off.. YES.. It's another bulletin generator for PCBoard
  33.         (aren't there about 10,000 already out there?). Well here's WHY I
  34.         made this one.
  35.  
  36.  
  37. /////////////////////////////////////////////////////////////////////////////
  38. THE "OTHER" ONES
  39.  
  40.         At one point I had about 7 different programs to make individual
  41.         bulletins. It was getting a bit crazy - 7 different EXE's, 7
  42.         different CFG files, 7 different command line parameter sets..ugh.
  43.  
  44.         The other thing I didn't like about the "other" ones is that
  45.         they were very 'un'configurable.
  46.  
  47.  
  48. /////////////////////////////////////////////////////////////////////////////
  49. TOPBLT - Complete User Statistics
  50.  
  51.         TOPBLT was designed to generate ALL the other bulletin types from
  52.         within ONE program. As well, it is VERY configurable as to what
  53.         the final output will look like, and I've only just begun.. :)
  54.  
  55.  
  56.         TOPBLT will create best/worst user statistics for the following
  57.         areas:  # of files uploaded
  58.                 # of files downloaded
  59.                 # of messages posted
  60.                 # of message read
  61.                 # of calls to the system
  62.                 Post:Call ratio
  63.  
  64.         As well, the bulletin colours, headers and style format are all
  65.         configurable through command line arguments.
  66.  
  67.  
  68. /////////////////////////////////////////////////////////////////////////////
  69. SETUP, CONFIGURATION
  70.  
  71.         There are no REQUIRED configuration files (although a colour
  72.         configuration file can be supplied). Everything is done through
  73.         command line arguments.
  74.  
  75.         **** NOTE ****
  76.  
  77.         YOU MUST HAVE SORT.EXE (the DOS program) SOMEWHERE IN THE PATH!!
  78.  
  79.         TOPBLT MAKES A SYSTEM CALL TO USE THIS PROGRAM AND WILL NOT FUNCTION
  80.         PROPERLY WITHOUT IT! (yes this is shoddy programming but it's also
  81.         a heck of a lot easier, so I don't want to hear any complaints..)
  82.  
  83.  
  84. /////////////////////////////////////////////////////////////////////////////
  85. USAGE, COMMAND LINE PARAMETERS
  86.  
  87.         TOPBLT <blt file> <users file> [options]
  88.  
  89.         <blt file>      - The path/name destination file for the bulletin.
  90.         <users file>    - The path/name of the PCBoard USERS file.
  91.  
  92.                           These two parameters are REQUIRED.
  93.  
  94.         [options]
  95.  
  96.         /MAX:[#]              - Specify how many users to include in the
  97.                                 bulletin. Default is 10.
  98.  
  99.         /HDR:[filename.ext]   - Path/name of a header file to insert at the
  100.              [GENERATE]         top of the bulletin. Default is no header
  101.                                 file.
  102.                               - If you use the keyword GENERATE instead of
  103.                                 a filename, TOPBLT will generate it's own
  104.                                 header which will simply consist of the type
  105.                                 of bulletin being generated.
  106.                                 ie: "Best 30 Message Posters Bulletin"
  107.  
  108.         /COL:[filename.ext]   - Path/name of a config file for custom colour
  109.                                 settings. Default is no colour config file.
  110.  
  111.         /TMP:[filename.ext]   - Supply your own name for the temporary file.
  112.                                 Default name for the temporary file is
  113.                                 TEMPFILE.$$$ in the current directory. This
  114.                                 option is supplied so that you can be sure
  115.                                 none of your files will ever be overwritten
  116.                                 with a temporary file.
  117.  
  118.         /EXC:[filename.ext]   - Path/name of an ascii file containing names
  119.                                 of users who you wish to be EXCLUDED from
  120.                                 the bulletin. One name per line.
  121.  
  122.         /CLR:[NONE/ANSI/PCB]  - Type of colour codes to use in file. Default
  123.                                 is PCBoard @X colour codes. A choice of NONE
  124.                                 will insert NO colour codes and produce a
  125.                                 straight ASCII file.
  126.  
  127.         /STY:[1-7]            - Style/Format for the bulletin. Default style
  128.                                 is #1. See sample files in this archive for
  129.                                 examples of each style.
  130.  
  131.         /TYP:[blt type][:LOW] - PCR     - Create Post:Call Ratios blt.
  132.                               - ULS     - Create Uploaders - # Files blt.
  133.                               - DLS     - Create Downloaders - # Files blt.
  134.                               - CALLS   - Create # of Calls blt.
  135.                               - POSTS   - Create # of Messages Posted blt.
  136.                               - MSGREAD - Create # of Messages Read blt.
  137.  
  138.                               - :LOW added to any type makes a 'Worst Users'
  139.                                 list. (ie: lowest # of posts)
  140.  
  141.                                 Default setting is /TYP:POSTS - Top Message
  142.                                 Posters bulletin.
  143.  
  144.         /DAT                  - This switch will simply cause TOPBLT to
  145.                                 add a little note to the end of the bulletin
  146.                                 saying what time and date the bulletin was
  147.                                 created on.
  148.  
  149.  
  150. EXAMPLES
  151. --------
  152.  
  153. TOPBLT d:\bbs\blt7 d:\bbs\main\users
  154.  
  155.         This is the minimum command line. Create a TOP 10 MESSAGE POSTERS
  156.         bulletin. Use PCBoard @X codes (default). Read the information
  157.         from D:\BBS\MAIN\USERS and output it to D:\BBS\BLT7.
  158.  
  159. TOPBLT c:\pcb\gen\blt10g c:\pcb\main\users /typ:posts:low /clr:ansi /max:20
  160.  
  161.         Create a WORST 20 MESSAGE POSTERS bulletin. Use ANSI codes. Read
  162.         the information from the USERS file in C:\PCB\MAIN. Output the
  163.         bulletin to the file C:\PCB\GEN\BLT10G.
  164.  
  165. TOPBLT blt5 e:\main\users /typ:calls /hdr:topcalls.hdr /sty:4 /col:calls.col
  166.  
  167.         Create a TOP 10 CALLERS bulletin (10 is the default number). Place
  168.         the file TOPCALLS.HDR in the beginning of the bulletin as a header.
  169.         Use style #4 to format the bulletin. Use the colours specified in
  170.         the colour configuration file CALLS.COL. Output the bulletin to
  171.         the file BLT5 in the current directory. The output will be using
  172.         PCBoard @X colour codes (default).
  173.  
  174. TOPBLT d:\gen\blt1 e:\main\users /clr:none /typ:msgread:low /max:5 /dat
  175.  
  176.         Create a WORST 5 MESSAGE READERS bulletin. Output the bulletin as
  177.         an ASCII file with no colour codes. Write the bulletin to the
  178.         file D:\GEN\BLT1. Add the time and date stamp to the end.
  179.  
  180.         ---
  181.         The options can be in any order AFTER the first 2 required
  182.         parameters and are not case sensitive.
  183.  
  184.         If the same parameter is used more than once on the command line,
  185.         the LAST use of it will be the one used.
  186.  
  187.  
  188. /////////////////////////////////////////////////////////////////////////////
  189. COLOUR CONFIGURATION FILE
  190.  
  191.         See the sample colour configuration file TOPBLT.COL for the
  192.         proper format.
  193.  
  194.         Note: The colour configuration file for TOPBLT v0.9 has one extra
  195.               entry on the end which is the Generated Header text colour,
  196.               so if you were using TOPBLT v0.8, make sure you add this
  197.               line to the colour configuration file.
  198.  
  199.  
  200. /////////////////////////////////////////////////////////////////////////////
  201. PROBLEMS AND SUPPORT
  202.  
  203.         Testing this program out isn't easy, as I don't run a BBS and
  204.         there are limited places where I may test it.
  205.  
  206.         So far it has been tested on only two systems - one with a user
  207.         base of approx. 50 users, the other with about 150 users. So far,
  208.         there have been no noticeable bugs (famous last words). It has
  209.         also now been tested in a multinode environment with file sharing
  210.         activities. It's run without problems on an IBM PS/2 30, a
  211.         Compaq DeskPro 386/33, and a no-name 486-33.
  212.  
  213.         If you have any problems or notice any bugs, PLEASE let me know.
  214.         I can be reached through the PCBHINTS or IBM conference on the
  215.         NorthAmeriNet (NANET) Network or, directly on Canada Remote
  216.         Systems (CRS).
  217.  
  218.         Even if you don't have problems, but you'd like to see ANY kind
  219.         of a change, don't hesitate to tell me!
  220.  
  221.  
  222. /////////////////////////////////////////////////////////////////////////////
  223. REGISTRATION
  224.  
  225.         Huh? Registration? I thought this was free?
  226.  
  227.         This program IS free and may be used by anyone who feels like doing
  228.         so. However, you are not allowed to remove the Copyright Statement,
  229.         or to sell this program, or bundle it with other (commercial)
  230.         goods. You may give it to anyone and distribute anywhere it, but
  231.         only in its original form with the complete documentation and all
  232.         support files.
  233.  
  234.         If you feel like sending a small donation ($5) or just a postcard
  235.         towards continuation of this and other PCBoard utilities (or perhaps
  236.         my university tuition), or just to say hi, feel free to do so!
  237.  
  238.         Please send all donations, postcards, comments/suggestions
  239.         (positive or negative) to:
  240.                                      Kendall Anderson
  241.                                      486 Aspen Forest Drive
  242.                                      Oakville, Ontario
  243.                                      L6J 6H7
  244.                                      CANADA
  245.  
  246.  
  247.         The source code (Turbo C) IS available, but for a price of $30.
  248.         I'm requesting $30 because I don't really want to give it out, and
  249.         I don't know many people who will want to shell out that much for
  250.         this program. Send me a mailing address or phone number and I'll
  251.         either upload it to you or send you a printed copy of the most
  252.         recent version.
  253.  
  254.  
  255. /////////////////////////////////////////////////////////////////////////////
  256. OPERATIONAL DETAILS
  257.  
  258.         TOPBLT directly reads the USERS and USERS.INF files from PCBoard.
  259.         This will NOT work if they are encrypted in any way! TOPBLT will
  260.         (starting with TOPBLT v0.9b) open the files in a shared, deny-write
  261.         mode - meaning, TOPBLT will not allow other programs to modify the
  262.         USERS and USERS.INF files while reading from them. This allows you
  263.         to create the bulletins while nodes are online.
  264.  
  265.         It then takes the information it needs from the files and generates
  266.         a temporary file (TEMPFILE.$$$) based on the supplied information.
  267.  
  268.         From here, the temporary file is sorted via the DOS program
  269.         SORT.EXE and is formatted into the final bulletin file. The SORT
  270.         program MUST be in the DOS path in order for TOPBLT to work
  271.         properly!
  272.  
  273.  
  274. /////////////////////////////////////////////////////////////////////////////
  275. DISCLAIMER AND OTHER STUFF
  276.  
  277.         I will not be held liable for any misfortune that may or may not
  278.         happen to you, which may or may not be the result of using or not
  279.         using this program. In other words, the usual disclaimer applies
  280.         here.
  281.  
  282.         This Top Bulletins Generator program is provides "AS IS" with no
  283.         claims regarding its usefullness or functionality. You, the user,
  284.         accept full responsibilty and libility for any problems or damages
  285.         associated with its operation.
  286.  
  287.  
  288. /////////////////////////////////////////////////////////////////////////////
  289. PLANS FOR TOPBLT v1.0 AND BEYOND.. (if we ever get that far..)
  290.  
  291.         - Top Uploaders in KBytes and Top Downloaders in KBytes.
  292.  
  293.                 This SHOULD have been included in this version but for some
  294.                 reason it's not reading in properly.. again to be fixed
  295.                 (hopefully) at a later date.
  296.  
  297.         - More configurability in output. Multi columnar displays. Multiple
  298.           reports side by side - ie: One bulletin with the Top Uploaders
  299.                                      AND Top Downloaders side by side.
  300.  
  301.         - And anything else that users request.. :)
  302.  
  303.  
  304. /////////////////////////////////////////////////////////////////////////////
  305. EXITING ERRORLEVELS
  306.  
  307.      Error  Description
  308.  
  309.         1   Successful exit.
  310.         8   Bulletin type specified with /TYP: parameter doesn't exist.
  311.                         (Check you command line arguments)
  312.         9   Style type specified with /STY: parameter doesn't exist.
  313.                         (Check command line)
  314.        10   Couldn't open file/file not found or doesn't exist.
  315.                         (Check your command line arguments)
  316.        17   Error trying to read current temporary file. (Possible disk error)
  317.        18   Error reading in data. (File structure possibly corrupt)
  318.        19   Error trying to create file.
  319.        20   Error trying to delete temporary file.
  320.        30   Insufficient number of command line arguments.
  321.        40   SORT.EXE was not found in the DOS path.
  322.  
  323.  
  324. /////////////////////////////////////////////////////////////////////////////
  325. REGISTERED TRADEMARKS
  326.  
  327.    All programs mentioned are copyrighted and/or trademarked by their
  328.    respective holders. Please refer to each respective program to determine
  329.    the actual copyright/trademark holder as appropriate or needed.
  330.  
  331.    PCBoard - Copyrighted: Clarke Development Company
  332.    Turbo C - Copyrighted: Borland International
  333.  
  334.  
  335. /////////////////////////////////////////////////////////////////////////////
  336. CREDITS
  337.  
  338.         Thanks to:
  339.  
  340.            - Shaun - as a matter of fact I AM compiling right now!
  341.            - Giggy - SIM boy, how's the XT doing? :)
  342.            - Kerry - for letting me test this out on your system (whether
  343.                         you wanted it or not :) )
  344.            - HJQ   - just because..
  345.  
  346.  
  347. /////////////////////////////////////////////////////////////////////////////
  348. FINALLY..
  349.  
  350.         Look in the file WHATS.NEW to see new changes and additions since
  351.         the last major version.
  352.  
  353.         Look in the file HISTORY.DOC to see a complete listing of the changes,
  354.         fixes and updates since the creation of TOPBLT.
  355.  
  356.  
  357. <EOF>
  358.